Python POC for GitHub-based API Reviews#47203
Open
tjprescott wants to merge 34 commits into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new repo script (scripts/generate_api_text.py) to generate a package-level API.md by building a wheel, running apiview-stub-generator (apistub) to produce the token JSON, and converting that JSON to markdown via Export-APIViewMarkdown.ps1. This is repo tooling intended to streamline API review artifact generation.
Changes:
- Introduces
scripts/generate_api_text.pyto locate a package undersdk/*/, build a wheel, runapistub, and emitAPI.mdinto the package directory. - Adds logic to install
eng/apiview_reqs.txtand (optionally) upgradeapiview-stub-generatorfrom the Azure SDK package index. - Uses
eng/common/scripts/Export-APIViewMarkdown.ps1to convert the generated*_python.jsontoken file into markdown.
tjprescott
force-pushed
the
GenerateAPITextScript
branch
3 times, most recently
from
7c45b15 to
b9dc383
Compare
tjprescott
force-pushed
the
GenerateAPITextScript
branch
from
b9dc383 to
ebb3870
Compare
tjprescott
changed the title
tjprescott
force-pushed
the
GenerateAPITextScript
branch
from
f320bdb to
e4b2876
Compare
mikeharder
reviewed
Jun 2, 2026
mikeharder
reviewed
Jun 2, 2026
tjprescott
force-pushed
the
GenerateAPITextScript
branch
3 times, most recently
from
6d81d65 to
818a5ee
Compare
tjprescott
force-pushed
the
GenerateAPITextScript
branch
from
818a5ee to
778edda
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 30 out of 30 changed files in this pull request and generated 6 comments.
Comments suppressed due to low confidence (1)
scripts/api_md_workflow/README.md:112
- Same issue later in the README: the printed regeneration command uses
--dest-dir .and omits--install-deps, which won’t reproduce the CI behavior and will write files to the wrong directory when run from the repo root. This should point--dest-dirat the package directory and include--install-deps.
4. `regenerate.js` rebuilds `api.md` for those packages.
5. `find_mismatches.js` records any `api.md` drift, including missing or untracked `api.md` files.
6. If drift is found, the workflow fails and prints the affected packages plus the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir .` command to regenerate each `api.md` file locally from the repository root.
778edda to
a82a7ee
Compare
tjprescott
force-pushed
the
GenerateAPITextScript
branch
from
804d5e8 to
8d07492
Compare
mikeharder
reviewed
Jun 6, 2026
mikeharder
reviewed
Jun 6, 2026
tjprescott
force-pushed
the
GenerateAPITextScript
branch
from
74f5a34 to
8fdfca0
Compare
kashifkhan
reviewed
Jun 8, 2026
kashifkhan
reviewed
Jun 8, 2026
kashifkhan
reviewed
Jun 8, 2026
kashifkhan
reviewed
Jun 8, 2026
kashifkhan
reviewed
Jun 8, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds tooling for GitHub-native API reviews for the Python SDK, enabling API surface tracking and review via GitHub PRs and CI. Based on this proposal: Proposal: API Reviews via GitHub (azure-sdk-tools#15789).
What's Included
1. CI Consistency Check (
.github/workflows/api-consistency.yml)A GitHub Actions workflow that enforces
API.mdconsistency on every PR that touchessdk/**:find_affected.js— diffs the PR against the base branch to find changed packagesregenerate.js— runsazpysdk apistub --md --extract-metadatafor each affected packagefind_mismatches.js— compares the regeneratedAPI.mdto the committed version and validates select metadata fields2. API Review PR Creator (
create_api_review_pr.js)A CLI tool to create dedicated API review PRs:
API.mdfor both the base tag and target branch3. Language Adapter Pattern (
scripts/api_md_workflow/)Core orchestration is language-agnostic. A per-repo adapter (
adapters/python.js) implements the language-specific logic (isPackageDir,findPackageDir,readVersion,generateApiForPackage). This allows the same framework to be ported to other Azure SDK language repos.4. Shared Utility Layer (
.github/shared/)Common ESM modules for subprocess execution, logging, path manipulation, and GitHub API interactions — shared across workflow scripts.
Examples
Auto Reviews
PR Review